.\" Copyright 2008-2010 Vadim Zhukov <persgray@gmail.com>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright notice,
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY AGAVA COMPANY ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
.\" EVENT SHALL THE AGAVA COMPANY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" The views and conclusions contained in the software and documentation are
.\" those of the authors and should not be interpreted as representing official
.\" policies, either expressed or implied, of the AGAVA Company.
.Dd $Mdocdate$
.Dt RB 7 URM
.Os AGAVA
.Sh NAME
.Nm rb
.Nd tools for backing up and restoring remote hosts
.Sh DESCRIPTION
.Nm
tools consists of 5 programs:
.Bl -tag -width "rb_restore(1)"
.It Xr rb_agent 1
Designed to be run on remote host.
Provides neccessary support for creating, putting and restoring archives.
.It Xr rb_cpanel 1
Wrapper to rb_restore, designed to create safe, read-only access to archives of
cPanel-based hosting clients data.
.It Xr rb_dump 1
Download (with help of
.Xr rb_agent 1 )
archives from remote hosts into archive catalog.
.It Xr rb_fixinfo 1
Help to fix archive information files after major RB upgrade.
.It Xr rb_restore 1
Provides interface to view information about stored archives, put them on remote
host or restore data from those archives on remote host.
.It Xr rb_rotate 1
Rotates outdated archives in archive catalog.
.El
.Sh PROFILES
Each archive is made using information from INI-like configuration file, called
.Cm profile .
Profiles describe what, where and how to dump and save.
Each profile contains one or more set of items to backup, called (backup)
modules.
.\" Each profile is divided in sections.
.\" There should be one global section and one or more module sections.
.\" Each section consists of directives in the form
.\" .Dl parameter \&= value .
For more information about profiles, see
.Xr rb 5 .
.Sh ARCHIVE CATALOG STRUCTURE
For each dumped host there is derectory hierarchy created on the backup server.
There is a base directory, called
.Dq archive directory ,
which contains global log file named
.Pa rb.log
and subdirectories for hosts being served.
In each host subdirectory host log named
.Pa rb.log
and subdirectories for each backup module reside.
Modules, in turn, can have their own subdirectories of any deep level, depending
on directives in profile (particulary,
.Va separate_archives
and
.Va what
directives).
.Sh SETTING UP DUMPS
At first you have to create system user on each remote host
.Xr rb 7
tools will connect to (say,
.Dq rb )
and one system user on a backup server (say,
.Dq dump .
Also you'll need a pair of SSH keys.
.Pp
Put private key in any file you like on a backup server and public key into
.Pa ~rb/.ssh/authorized_keys
on each remote host.
For details on setting up keyed authentiphication see
.Xr sshd 8 .
.Pp
You have to use same username on all hosts to be backed up that belong to same
profile.
You can use bundled
.Pa cpanel
folder as a source for making automated installations.
Just copy the folder to remote host and run
.Dq make install .
.Pp
Then, on a backup server, proceed the following steps:
.Bl -enum -compact
.It
Create profile (or use existing), preferrably in
.Pa ~/.rb/
because it'll allow to use more readable short form of profile path:
.Bd -literal
[global]
# If ssh_* directives not specified, ssh(1) will try
# to determine them on its own
ssh_identity = /path/to/private/key
ssh_user = rb
# If not specified, ~/dumps will be used
archive_dir = /path/to/dumps
# If yes, archives will be automatically rotated after each dump
autorotate = yes
<...>
.Ed
.Pp
.It
Create archive directory (same as specified in profile).
.It
Make a test connection to all remote hosts to be backed up:
.Dl $ for H in host1 host2 host3; do ssh -v rb@$H :; done
Make sure
.Xr ssh 1
do not ask you anything when connecting.
.It
Make a test dump:
.Dl $ rb_dump -v profile host1 host2 host3
If any errors occur, resolve them now.
.It
Backup server: put
.Xr rb_dump 1
call into
.Xr crontab 5 ,
for example:
.Dl 0 3 * * * rb_dump profile host1 host2 host3
.El
Remember to check the logs or mails sent by
.Xr cron 8
for errors after during dump.
.Sh SEE ALSO
.Xr rb_agent 1 ,
.Xr rb_cpanel 1 ,
.Xr rb_dump 1 ,
.Xr rb_fixinfo 1 ,
.Xr rb_restore 1 ,
.Xr rb_rotate 1 ,
.Xr rb 5
.Sh AUTHORS
The
.Nm
manual page was written by
.An Vadim Zhukov Aq persgray@gmail.com .
